BBS Toolkit/BBS Toolkit.iso/wildcat/w3euti25.zip/UTI.DOC

Text File | 1993-02-10 | 29KB | 805 lines

┌───────────────────────────────────────────────┐
│ WC3 Enhanced UTIs      v2.5         02-10-93  │
└───────────────────────────────────────────────┘


What They Do
------------

UTIs (Universal Text Interface) are a group of programs that allow
the PC Relay and MegaMail door programs to interface with a BBS.
There are many different UTI programs available and each works with
a specific BBS program.

UTI programs directly access the BBS database files and perform
functions such as message imports and exports, listing available
conferences and updating last-read pointers.  Thanks to the UTI
standard interface, PC Relay can be used with many different BBS
programs.

These UTIs are designed for use with WildCat versions 3.0x to 3.5x.
They will automatically detect which version you are using and
build the message databases accordingly.


Features
--------

1.   The UTI programs will work properly in a multi-node
     environment.  These two features have been added to achieve
     multi-node compatibility:

     A.   All imported messages are marked internally with a UTI
          code.  This code identifies the message as coming from
          the UTIs.  In multi-network situations, the code also
          identifies which network the message came from.  Imported
          messages will not be exported to the same network.

     B.   The UTIs keep their own high message numbers.  If a
          message is entered online and the PC Relay software
          misses it, the UTIs will detect it and adjust the next
          export accordingly.  PC Relay and communication errors
          are taken into account and will not confuse the UTI's
          high message count.

2.   Imported text files "<<*.IMP" are exported along with outgoing
     messages just like regular text.  Each time an *.IMP file is
     exported, a message will be logged to the UTI.LOG file.

3.   Input and output files are processed as binary files instead
     of text files.  Text files are limited in that an End-of-File
     mark (ASCII 26) within a message would cause an import to end
     prematurely, sometimes causing errors and often losing
     messages.  When an end-of-file mark is detected in the middle
     of a packet, a message will be logged to the UTI.LOG file.

4.   Extra spaces at the end of a line are skipped during imports
     and exports.  The blank lines surrounding the PC Relay
     taglines often have 30-40 extraneous spaces.  By eliminating
     these wasted characters, your MSGxxx.DAT files will be
     approximately 5% smaller.

5.   Using a combination of file buffers, smart file locking and
     batch processing, the Enhanced WC3 UTIs are approximately 11-
     200% faster than earlier WildCat UTIs.

Other Information
-----------------

1.   "Soft errors" such as corrupted messages and unexpected data
     will be logged to an error file and the message will be
     skipped.  Import or export will continue with the next good
     message, if any.

2.   "Hard errors" such as missing files, full disks and too many
     open files will be logged to an error file and cause the UTI
     to stop.  An error code will be passed to the calling program
     (PC Relay, MegaMail) which normally causes the calling program
     to stop.

3.   The mail waiting flag is set in both real name and alias
     conferences.

4.   Messages are limited to 150 lines of up to 79 characters per
     line.  Lower limits may be defined using the MAKEWILD program;
     If a message exceeds the conference's line limit it will be
     split into two or more parts.

     Excessive taglines sometimes make a message exceed its line
     limit.  To avoid unnecessary message splitting, a conference's
     line limit may be exceeded by up to 10 lines if there is ample
     space in the message record.  These additional lines are
     supported by WildCat and will not cause any problems.

5.   During an import, the UTIs will abide by the conference's
     maximum message limit.  If the number of messages exceeds that
     limit, the UTIs will delete excessive messages starting with
     the lowest message number until the message limit is reached.
     Messages marked with the "No Delete" flag will not be deleted.

6.   Pressing CTRL-C will signal the UTIs to stop processing at the
     next safe opportunity.  The UTIs will stop with an errorlevel,
     signalling to the calling program that it stopped abnormally.


Setup
-----

Install the parent program (PC Relay or the MegaMail Door)
according to that program's instructions.  The UTI programs can be
placed with the PC Relay program files, or in any directory that is
listed in the path.


DOS Environment Variables
-------------------------

The UTIs can use three optional environment variables.  DOS
environment variables are defined using the SET command.

WCHOME :  This variable is optional and contains the path to the
          main WildCat directory.  An example is:

               SET WCHOME=C:\WC30

          If this variable is not defined, the UTIs will search the
          path until the main WildCat directory is found.  If you
          use the WCHOME environment variable, the UTIs will take
          less time since they won't have to search for the WildCat
          directory.

WCNODEID: If you are running a multi-node BBS and do not have the
          MAKEWILD autonode option enabled, this variable must be
          set to a unique number between 1 and 250.  See the
          section on multi-node BBSs for more information.

UTINET :  With the advent of PC Relay 4.11, the UTINET variable
          will no longer function as it was designed.  PCR 4.11
          will not export messages with a PCR tagline, even if a
          conference needs to be sent to two or more networks.
          This feature is being retained for future use.

          This variable is only important if you cross two networks
          together.  If two or more PC Relay networks access the
          same message conference, you need to set this variable to
          a unique character for each conference.  For example:

          SET UTINET=A
          SET UTINET=B

          Only one character is required, and only the first
          character will be used if there is more than one.

MAXLINES: This environment variable will override the maximum message
          line setting in MakeWild.  This variable affects all
          conferences and works on import only (of course).  Example:

          SET MAXLINES=100

          Let's say a particular conference only allows 40 lines.
          You set MakeWild to 40 lines so your callers can't leave
          longer messages, but you don't want network messages split
          on import.  Using this variable gives you flexibility.
          (Optional)

UTILOG :  UTILOG environment variable added for trouble-shooting.
          If the UTILOG environment variable is set to "Yes" (or
          "on" or "full" or just about anything), then extra
           information will be logged to the UTI.LOG file each time
           UTIIMPRT & UTIEXPRT are run.  Example:

           SET UTILOG=YES

           To turn full logging off, type:

           SET UTILOG=


Multi-Node BBSs
---------------

If you are running a single-line version of WildCat, the UTIs
cannot be run while the BBS is up, or when any other utility is
accessing the message databases.

In order to use the UTIs while the BBS is online, you must be
running a multi-line WildCat version and have either DOS share or
Novell defined in the Makewild program.  If the MAKEWILD autonode
option is enabled, the UTIs will determine the proper node ID to
use.  If you are not using the autonode feature, the environment
variable WCNODEID must be set to a valid number between 1 and 250.

Use the following command:
     SET WCNODEID=3

using 3 or whichever node ID you wish to use.  This node ID must
not be duplicated.  No other BBS node or program using this node ID
may be running while the UTIs are accessing the message databases.


Renumbering the Databases
-------------------------

You must be careful when renumbering the databases.  Before you
renumber, make sure that all messages have been exported.  The best
method is to:

     1.  Take all BBS nodes down.
     2.  Run the PC Relay export program.

     You may renumber your conferences now, or wait until you
     import new messages.

Since the UTIs keep their own high message numbers, you must run
the UTIRESET program in addition to the PC Relay RESET program.
The UTIRESET program must be run in the directory where you run
your imports and exports.

If you use the UTINET environment variable, UTIRESET must be run
for each UTINET network.


Errors
------

Things to keep in mind when tracking down PostLink & UTI erros:

1)    There are three different log files that you need to check.
      PostLink uses POSTLINK.LOG and ERROR.LOG while the UTIs use
      UTI.LOG.

2)    PostLink does not report the entire error code to either the
      screen of the log files.  For the correct UTI error code,
      always check the UTI.LOG file.

Here are a list of the UTI error codes:

      DOS Runtime Error Codes:

        1 = Invalid function number.
        2 = File not found.
        3 = Path not found.
        4 = Too many open files.
        5 = File access denied.
        6 = Invalid file handles.
       12 = Invalid file access code.
       15 = Invalid drive number.
       16 = Cannot remove the current directory.
       17 = Cannot rename across drives.

      DOS I/O Errors:

      100 = Disk read error.
      101 = Disk write error.
      102 = File not assigned.
      103 = File not open.
      104 = File not open for input.
      105 = File not open for output.
      106 = Invalid numeric format.

      DOS Critical Errors:

      150 = Disk is write protected.
      151 = Unknown unit.
      152 = Drive not ready.
      153 = Unknown command.
      154 = CRC error in data.
      155 = Bad drive request structure length.
      156 = Disk seek error.
      157 = Unknown media type.
      158 = Sector not found.
      159 = Printer out of paper.
      160 = Device write fault.
      161 = Device read fault.
      162 = Hardware failure.

      DOS Fatal Errors:

      200 = Division by zero.
      201 = Range check error.
      202 = Stack overflow error.
      203 = Heap overflow error.
      204 = Invalid pointer operation.
      205 = Floating point overflow.
      206 = Floating point underflow.
      207 = Invalid floating point operation.
      208 = Overlay manager not installed
      209 = Overlay file read error.
      210 = Object not initialized.
      211 = Call to abstract method.
      212 = Stream registration error.
      213 = Collection index out of range.
      214 = Collection overflow error.
      215 = Arithmatic overflow error.


      Special UTI Error Code:

      255 = Indicates one of the following:
            - Control-C was pressed during operation.
            - Invalid or incorrect number of parameters.


      BTree Isam Error Message List:

       9500..
       9899  =  DOS I/O Error.  Subtract 9500 from the error number to
                find the actual DOS I/O error code.

       9900  =  Invalid path name.

       9901  =  Too many open files.

       9902  =  Current directory is full.

       9903  =  File not found.

       9904  =  Invalid file handle.

       9905  =  Read request exceeds 64K bytes.

       9906  =  Write request exceeds 64K bytes.

       9908  =  Invalid access mode.

      10000  =  Insufficient memory to initialize the BTree routines.

      10001..
      10009  =  Serious I/O error occurred while in save mode.  The fileblock
                is still in a usable state but the last operation was not
                completed.

      10010  =  Index file is probably corrupt, ie: it was not closed properly
                after the last modification.  Can be corrected by a rebuild.

      10020  =  Record length less than 22 or more than 2147483647 bytes.

      10030,
      10040  =  Insufficient memory for Fileblock descriptors.

      10050  =  Invalid number of keys specified.

      10055  =  Key length is too long.

      10060  =  Too many keys, or file read error.

      10070  =  File read error:
                - Dialog file may be corrupted from a previous program run
                  (deleting the dialog file may help).
                - Tried to read beyond the end of the file.
                - Physical hard disk error.

      10075  =  File write error.

      10080  =  Fileblock not open.

      10090,
      10100  =  Insufficient memory to allocate Fileblock.

      10110  =  Drive not ready.

      10120  =  «PageSize» incompatible with Fileblock.

      10121  =  «MaxKeyLen» too small.

      10125  =  Passed key is too long.

      10130,
      10135  =  Record 0 must not be accessed.

      10140  =  Access not possible, undefined error.

      10150  =  Out of file handles when trying to flush network fileblocks.

      10160  =  Fileblock not correctly closed.

      10164  =  Invalid key number.

      10170  =  Fileblock free record list is corrupt. (Rebuild)

      10180  =  Attempt to repair Fileblock failed.

      10190  =  Extend handle function requires DOS 3.3 or later.

      10191  =  Insufficient memory for new file handle table.
      10192  =  Unable to initialize new file handle table.

      10200  =  No matching key found.

      10205  =  Data record is currently locked.

      10210  =  No key found and no larger keys available.

      10220  =  Key to delete was not found.

      10230  =  Cannot add duplicate key.

      10240  =  No larger key found.

      10245  =  No smaller key found.

      10250  =  No larger key found.

      10255  =  Sequential access not allowed.

      10260  =  No smaller key found.

      10265  =  Sequential access not allowed.

      10270  =  No matching key and record number found.

      10280,
      10285  =  Index empty.

      10303  =  Out of workstation numbers.

      10305  =  Unable to access workstation log file.

      10310  =  Network initialization error.

      10315  =  Network exit error.

      10322,
      10323  =  Close of fileblock not possible because of a non
                removeable lock.

      10330  =  Fileblock lock attempt failed.

      10332  =  Fileblock readlock attempt failed.

      10335  =  Record lock attempt failed.

      10337  =  Insufficient memory for lock list.

      10340..
      10342  =  Fileblock unlock attempt failed.

      10345  =  Record unlock attempt failed.

      10355  =  A lock prevents the operation.

      10356  =  Insufficient memory to allocate Fileblock.

      10397  =  A lock prevents the operation.

      10398  =  Fileblock must be locked for the operation.

      10399  =  A lock prevents the operation.

      10410  =  Data file not found.

      10411  =  Insufficient heap space for work buffers.

      10412  =  Record section length exceeds 64K.

      10415  =  Too many segments in a variable record.

      10420,
      10425  =  Relative position or scale invalid.

      10430  =  Fileblock repair in read only mode not allowed.

      10435  =  Index tree page greater than 16k.

      10440  =  Cannot create dialog file in read only mode.

      10445  =  Fileblock pointer or descriptor corrupted.

      10450  =  BTree routines have already been initialized.

      10455  =  Must initialize the BTree routines first.

      10460  =  Reorganization aborted.


Error Log File
--------------

The UTIs will record error messages to the file UTI.LOG in the
current directory.  Other events will also be logged, including:

     1.   Messages split into two or more parts.
     2.   Messages skipped due to errors.
     3.   *.IMP text files exported as part of a message.
     4.   New, non-exported messages detected during an import.
     5.   End-of-file marks detected in the middle of an import
          packet.  This is only for informational purposes; EOF
          marks have no effect on the enhanced UTIs.


Program Descriptions
--------------------
The input and output files are standard text files and follow the
UTI v2.1 specifications.  The UTI format is designed and controlled
by Kip Compton; requests for additional UTI format information
should be addressed to him.


UTIEXPRT

Exports messages from the specified conference starting with the
message number in parameter #2.  At this time, WildCat does not
have a no-echo option, so all messages will be exported.

The exception is when the /NETWORK parameter is specified.  When in
Network mode, messages that were imported from the same network ID
will not be exported.  The UTINET environment variable can be used
to change network Ids, or the default ID "0" will be used.

Network mode also enables the multi-node features.  UTIEXPRT keeps
track of its own high message numbers in the UTINETx.DAT file,
where "x" is the UTINET environment variable.  These separate high
message numbers ensure that all appropriate messages will be
exported to the network.

     Parameter 1 -  Conference number.
     Parameter 2 -  First message number to export.
     Parameter 3 -  Full path and file name of the output file.
     Parameter 4 -  /NETWORK (optional)


UTIIMPRT

Imports new messages from the input file into the specified
conference.  In Network mode, it internally marks each message with
a network code which will prevent the message from being exported
to the same network.

PC Relay pre-assigns each message a number before calling the
UTIIMPRT program.  Unless PC Relay is told otherwise, it assumes
that these message numbers will stay the same when imported into
the message conference.  If the first message number in the input
file is different than the message number used on the BBS, then the
difference is written to the adjustment file (parameter 3).

PC Relay uses the adjustment file to keep its reference numbers
accurate, however the numbers may not be accurate when:

     1.   New messages are added to the BBS while an import is in
          progress.
     2.   Invalid or corrupted messages are skipped.
     3.   Long messages are split into two or more parts.


The UTIs can tell PC Relay to adjust all the reference numbers in
an import, but there is no way to change just a few of them.
WildCat limits messages to a maximum of 12000 bytes.  The internal
WC editors are more restrictive:  When used to create a message,
the limit is 150 lines of 72 characters each, however, the editors
will allow you to safely edit an existing message of up to 164
lines of 72 characters each.  This allows full sized messages (150
lines from the source BBS) to be imported even after many taglines
have been added.

     Parameter 1 -  Conference number.
     Parameter 2 -  Full path and file name of the input file.
     Parameter 3 -  Full path and file name of the message number
                    adjustment file.  (Optional)
     Parameter 3 -  /NETWORK  (Optional)
          or   4


UTIHIGH

Reads the conference status record and writes the high message
number to the output file.

     Parameter 1 -  Conference number.
     Parameter 2 -  Full path and file name of the output file.


UTILIST

Creates a list of available conferences with their descriptions.
This list is used in the PC Relay CONFIG program and in the
MegaMail door.

     Parameter 1 -  Full path and file name of the output file.


UTIVER

Writes the UTI version number to the output file.  A second line
identifies the UTI author and/or program name.

     Parameter 1 -  Full path and file name of the output file.


UTILSTRD  (MegaMail only)

Depending on the first parameter, this program will either READ the
specified user's last read message numbers or WRITE (update) the
last read message numbers.  Output from this program will be
matched against output from UTILIST to determine which conferences
the user may access and his/her last read pointer.

     Parameter 1 -  READ or WRITE
     Parameter 2 -  Full path and file name of the input or output
                    file.
     Parameter 3 -  The user's first, middle, last name, etc.

UTIDOOR   (MegaMail only)

Creates a small door information file for use by the MegaMail door.
This program reads the DOOR.SYS file and creates the output file,
which should be UTIDOOR.TXT.

     Parameter 1 -  Full path and file name of the output file.


UTIRFLAG  (MegaMail only)

Clears a user's mail-waiting flag for a specified range of
messages.  After a user downloads messages using the MegaMail door,
this program is called to clear the mail-waiting flags.

     Parameter 1 -  Conference number.
     Parameter 2 -  Starting message number.
     Parameter 3 -  Ending message number.
     Parameter 4 -  The user's first, middle, last name, etc.


UTIRESET

This program is unique to the Enhanced UTIs; it resets the high
message numbers in the UTINETx.DAT file.  This should be run when
the message conferences are renumbered and whenever the PC Relay
"RESET" program is run.


Registration
------------

The Enhanced WC3 UTI programs are distributed as shareware.
Shareware software allows you to try before you buy, thus you never
need to pay for a shareware program that does not meet your needs.

You may use these UTIs for 30 days at no charge, allowing you a
chance to see if they meet your needs.  If you keep using them
after 30 days, you must register the software by sending in the
registration form and paying the registration fee of $20 (US).
Registered DupMsg users are entitled to a $5 discount.

Registration entitles the purchaser to use the UTIs on one BBS
system.  A BBS system is defined as either a single computer
system, or a network system where multiple computers are connected
by direct cable to the same network server.

Even after you register these UTIs, your satisfaction is
guaranteed.  If within 30 days after registering you decide that
you no longer wish to use the programs, simply write a letter to
the author requesting a refund and your registration fee will be
refunded.  Only the registration fee will be refunded, not the cost
of diskettes that may have been ordered.

Support
-------

The author can be reached via the WildNet, FidoNet and MSInet mail
networks.  Please address messages to Jim Metzler.

Registration fees and requests for additional information should be
addressed to:

     Jim Metzler
     WPI Box 188
     100 Institute Road
     Worcester, MA 01609

     Voice: [phone]
     BBS:   [phone]


Distribution
------------
Several WildNet Sysops have agreed to post DupMsg, the Enhanced
UTIs and Censor in their original ARJ archive with Security
Envelope.  Thanks go to these Sysops and the many others who
have supported these programs.


The original archive may be downloaded from the following BBSs:

Miwok Village        --  Worcester, MA         --  [phone]
MSI HQ BBS           --  Bakersfield, CA       --  [phone]

B-Line BBS           --  Bakersfield, CA       --  [phone]
Bun's BBS            --  San Francisco, CA     --  [phone]
Lost BBS             --  Overland Park, KS     --  [phone]
NoHo BBS             --  Hesperia, CA          --  [phone]

Data Base Forum      --  Oslo, Norway          --  [phone]
Gil's PC             --  Chapeau, Quebec       --  [phone]


DupMsg, Censor and the Enhanced UTIs can be F'Reqed from:

     Lost BBS           --  Compucom, V.32     --  (1:280/319)
     B-Line BBS         --  HST Dual Std.      --  (1:210/46)

The request names are 'DUPMSG', 'CENSOR' and 'UTI'.


You are authorized to distribute the Enhanced UTIs provided the
executable programs, documentation, and registration form are
included in their original, unmodified state.  No fee may be
charged for the distribution of DupMsg without the express
written permission of the author.


Warranty Disclosure
-------------------

Normally, software distributed through bulletin boards systems or
shared from one user to another does not carry a warranty, mainly
because the author does not have control over the product and the
program can be modified either intentionally or accidentally
without the author's knowledge.

Recognizing this, these UTI programs carry either no warranty or a
limited warranty depending on the distribution method.

LIMITED WARRANTY:

     This applies only when the program is received directly from
     the author on diskette, or when it is received in the original
     ARJ archive, complete with a valid Security Envelope.  The ARJ
     Security Envelope must read "ARJ archive created by James W.
     Metzler R#0301".  The user must keep the diskette or original
     ARJ archive as proof of this warranty.

   - What is covered:  The UTIs program will perform substantially
     as described in this document.  In addition, while the program
     may contain minor bugs or errors, it is warranted to be free
     of major defects for a period of six months.  Diskettes
     received from the author are guaranteed to be free or defects
     for a period of six months from date of receipt.

   - What is not covered:  The author will not be liable for
     incidental and/or consequential damages, including injury to
     property, interruption of service, loss of business and/or
     anticipated profits, or other consequential damages that may
     result from use, malfunction or failure of the programs, or
     from errors or omissions in the documentation.  Some states do
     not allow the exclusion or limitation of incidental or
     consequential damages, so the above limitation may not apply
     to you.

     Any attempt to modify the UTI programs will void this warranty
     in its entirety.

   - If there is a problem:  Within 60 days of notification that a
     major defect exists, the author, at his discretion, will
     either fix the program and forward the replacement at no cost
     to the registered user, or will refund the registration fee.

     Defective diskettes will be replaced within 60 days at no cost
     to the purchaser.

   - How to get service:  Send a written letter to the author
     detailing the type of problem and symptoms experienced.
     Include your name, address, voice phone number and
     registration number and any additional information that you
     believe may be useful, such as any TSRs and disk cache
     programs in use.

     The author may contact you by voice or written letter for more
     information to help in tracking down the problem.

NO WARRANTY:

     If you did not receive the UTI programs directly from the
     author, or in its original ARJ archive with a genuine Security
     Envelope (see above), then there is a possibility that the
     programs and/or documentation have been modified, or that the
     program is not the author's work.  The author makes no
     warranty of any kind, express or implied, including any
     warranties of fitness and/or merchantability if the program
     was received from other sources.

     The author will not be liable for any damages, whether direct,
     indirect, special or consequential arising from a failure of
     this program to operate in the manner desired by the user.
     The author will not be liable for any damage to data or
     property which may be caused directly or indirectly by use of
     the program.

When trying new software, always backup any and all important files
on your system.


Special Thanks
--------------

Special thanks to Peter Anderson, Ralph Maya, Ryan Cramer, Bob
Allman, Bill Anton and Mike Callaghan for their help ßeta testing
these programs.  Their assistance has been invaluable in the
development of these programs.


Copyright
---------

These UTI programs are:
Copyright (c) 1992, James W. Metzler, All Rights Reserved.